codecs.StreamReader

Module codecs :: Class StreamReader

[show private | hide private]

Class StreamReader

Codec --+
        |
       StreamReader

Known Subclasses:: StreamReader

Method Summary
	`__init__(self, stream, errors)` Creates a StreamReader instance.
	`__enter__(self)`
	`__exit__(self, type, value, tb)`
	`__getattr__(self, name, getattr)` Inherit all other methods from the underlying stream.
	`__iter__(self)`
	`decode(self, input, errors)` Decodes the object input and returns a tuple (output object, length consumed).
	`next(self)` Return the next decoded line from the input stream.
	`read(self, size, chars, firstline)` Decodes data from the stream self.stream and returns the resulting object.
	`readline(self, size, keepends)` Read one line from the input stream and return the decoded data.
	`readlines(self, sizehint, keepends)` Read all lines available on the input stream and return them as list of lines.
	`reset(self)` Resets the codec buffers used for keeping state.
	`seek(self, offset, whence)` Set the input stream's current position.
Inherited from Codec
	`encode(self, input, errors)` Encodes the object input and returns a tuple (output object, length consumed).

Method Details

init(self, stream, errors='strict')
(Constructor)

Creates a StreamReader instance.

stream must be a file-like object open for reading
(binary) data.

The StreamReader may use different error handling
schemes by providing the errors keyword argument. These
parameters are predefined:

 'strict' - raise a ValueError (or a subclass)
 'ignore' - ignore the character and continue with the next
 'replace'- replace with a suitable replacement character;

The set of allowed parameter values can be extended via
register_error.

getattr(self, name, getattr=<built-in function getattr>)
(Qualification operator)

Inherit all other methods from the underlying stream.

decode(self, input, errors='strict')

Decodes the object input and returns a tuple (output object, length consumed).

input must be an object which provides the bf_getreadbuf buffer slot. Python strings, buffer objects and memory mapped files are examples of objects providing this slot.

errors defines the error handling to apply. It defaults to 'strict' handling.

The method may not store state in the Codec instance. Use StreamCodec for codecs which have to keep state in order to make encoding/decoding efficient.

The decoder must be able to handle zero length input and return an empty object of the output object type in this situation.

Overrides:: codecs.Codec.decode (inherited documentation)

next(self)

Return the next decoded line from the input stream.

read(self, size=-1, chars=-1, firstline=False)

Decodes data from the stream self.stream and returns the resulting object.

chars indicates the number of characters to read from the stream. read() will never return more than chars characters, but it might return less, if there are not enough characters available.

size indicates the approximate maximum number of bytes to read from the stream for decoding purposes. The decoder can modify this setting as appropriate. The default value -1 indicates to read and decode as much as possible. size is intended to prevent having to decode huge files in one step.

If firstline is true, and a UnicodeDecodeError happens after the first line terminator in the input only the first line will be returned, the rest of the input will be kept until the next call to read().

The method should use a greedy read strategy meaning that it should read as much data as is allowed within the definition of the encoding and the given size, e.g. if optional encoding endings or state markers are available on the stream, these should be read too.

readline(self, size=None, keepends=True)

Read one line from the input stream and return the decoded data.

size, if given, is passed as size argument to the read() method.

readlines(self, sizehint=None, keepends=True)

Read all lines available on the input stream and return them as list of lines.

Line breaks are implemented using the codec's decoder method and are included in the list entries.

sizehint, if given, is ignored since there is no efficient way to finding the true end-of-line.

reset(self)

Resets the codec buffers used for keeping state.

Note that no stream repositioning should take place. This method is primarily intended to be able to recover from decoding errors.

seek(self, offset, whence=0)

Set the input stream's current position.